<!doctype html public "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta name="robot" content="index,follow">
<title>Module log - Logging module - Forth Foundation Library</title>
</head>
<body>
<h2>log - Logging module</h2>
<h3>Module Description</h3>
<p>The log module implements a software logging and tracing module.
The module uses 6 different log events, from low to high: trace, debug,
info, warning, error and fatal. All log events will generate a log message.
Only the fatal log event will do an abort. A log message shows the
date and time, the log event and the actual message. The log events can be
skipped during compilation and suppressed during execution. This is done
by setting the log level with the log-level word. All log events that are
equal or higher then this level will be compiled c.q. accepted. All events
can be skipped by setting log.none to the log level.
A log message can be sent to one of the four so called appenders. The
default appender is the console. This appender is also used if one of the
file appenders is not able to write to a file. The second appender is a
normal text file. The third type appender is a rolling file appender. This
appender writes a number of log messages to the first file, then moves to
the next file and writes again a number of log messages, and so on, until
the number of files is reached. Then the appender starts again with the
first file. The calling word provides the base filename for the rolling
filename. The logging module appends ".1", ".2" and so on for the
different filenames. The last appender is the callback appender. With this
appender the calling module can process the messages by its own. The stack
notation for the callback word is: [ c-addr u -- ]
</p>
<h3>Module Words</h3>
<dl>
</dl>
<h4>Log events</h4>
<dl>
<dt><a name="word1"><b>log.trace</b>	( -- n )</dt>
<dd>the trace event</dd>
<dt><a name="word2"><b>log.debug</b>	( -- n )</dt>
<dd>the debug event</dd>
<dt><a name="word3"><b>log.info</b>	( -- n )</dt>
<dd>the info event</dd>
<dt><a name="word4"><b>log.warning</b>	( -- n )</dt>
<dd>the warning event</dd>
<dt><a name="word5"><b>log.error</b>	( -- n )</dt>
<dd>the error event</dd>
<dt><a name="word6"><b>log.fatal</b>	( -- n )</dt>
<dd>the fatal event</dd>
<dt><a name="word7"><b>log.none</b>	( -- n )</dt>
<dd>disable all events</dd>
</dl>
<h4>Appender words</h4>
<dl>
<dt><a name="word8"><b>log-to-rolling</b>	( c-addr u n1 n2 -- )</dt>
<dd>Start logging to rolling files, with names starting with c-addr u, maximum n1 files and n2 entries in one file</dd>
<dt><a name="word9"><b>log-to-file</b>	( fileid -- )</dt>
<dd>Start logging to the file</dd>
<dt><a name="word10"><b>log-to-callback</b>	( xt -- )</dt>
<dd>Start logging to the xt callback</dd>
<dt><a name="word11"><b>log-to-console</b>	( -- )</dt>
<dd>Start logging to the console</dd>
</dl>
<h4>Log settings words</h4>
<dl>
<dt><a name="word12"><b>log-from-level</b>	( n -- )</dt>
<dd>Skip and suppress all events below level n</dd>
<dt><a name="word13"><b>log-stack-depth</b>	( n -- )</dt>
<dd>Append max n top stack elements to the log message</dd>
<dt><a name="word14"><b>log-with-time&date</b>	( flag -- )</dt>
<dd>Set if the time&amp;date should start the log message</dd>
<dt><a name="word15"><b>log-with-flush</b>	( flag -- )</dt>
<dd>Set if the log line should be flushed to file</dd>
</dl>
<h4>Log word</h4>
<dl>
<dt><a name="word16"><b>do-log</b>	( c-addr u n -- )</dt>
<dd>Log the message c-addr u with event n</dd>
</dl>
<h4>Parsing log words</h4>
<dl>
<dt><a name="word17"><b>fatal"</b>	( "ccc&lt;quote&gt;" -- )</dt>
<dd>Log a fatal message</dd>
<dt><a name="word18"><b>error"</b>	( "ccc&lt;quote&gt;" -- )</dt>
<dd>Log an error message</dd>
<dt><a name="word19"><b>warning"</b>	( "ccc&lt;quote&gt;" -- )</dt>
<dd>Log a warning message</dd>
<dt><a name="word20"><b>info"</b>	( "ccc&lt;quote&gt;" -- )</dt>
<dd>Log an info message</dd>
<dt><a name="word21"><b>debug"</b>	( "ccc&lt;quote&gt;" -- )</dt>
<dd>Log a debug message</dd>
<dt><a name="word22"><b>trace"</b>	( "ccc&lt;quote&gt;" -- )</dt>
<dd>Log a trace message</dd>
</dl>
<h3>Examples</h3>
<pre>
include ffl/log.fs


.( Logging to the console:) cr

log-to-console

warning" Warning message"

log.error log-from-level          \ Log only errors and higher

warning" Skip warning message"

error" Error message"

log.trace log-from-level          \ Log all events


.( Logging to file "log.tmp" ) cr

s" log.tmp" w/o create-file 0= [IF]
  dup log-to-file

  trace" Trace message"

  info" Info message"

  close-file drop
[ELSE]
  drop
  .( Error: could not create "log.tmp" ) cr
[THEN]


.( Logging to rolling files: log.1 log.2 and log.3, 5 entries per file .." ) cr

s" log" 3 5 log-to-rolling

3 log-stack-depth            \ Log also the stack contents, maximum 3 values

: do-18logs
  18 0 DO
    info" Infos message via rolling files"
  LOOP
;

23 56                        \ Put some example values on the stack for the logger

do-18logs                    \ Generate 18 log messages in the rolling files

2drop


.( Logging to callback ) cr

: callback ( c-addr u -- )
  ." Logging:" type cr       \ Callback shows the message on the console
;

' callback log-to-callback

0 log-stack-depth            \ Stop logging the stack contents

error" Error message via callback"

debug" Debug message via callback"

</pre>
<hr>
<div align="center">generated 24-Jul-2010 by <b>ofcfrth-0.10.0</b></div>
</body>
</html>
